ASME's Mechanical Engine…ing Toolkit 1997 December/ASME's Mechanical Engineering Toolkit 1997 December.iso/c_lang/dos-dev.lzh/DOSDEV.DOC

Text File | 1986-03-21 | 22.3 KB | 385 lines

_Creating User-Installable Device Drivers in MS-DOS 2.0+_

               Bruce Bordner, 1985
               1713 4th Avenue
               Asbury Park, NJ 07712



  Prior to version 2.0, driver programs to support new (or non-IBM)
  peripherals required some complex and ugly programming to interface with
  DOS.  This became so much of a problem that it was fixed in the first major
  revision (2.0) by providing a "legal" way to install device drivers and
  interface with the DOS I/O functions.  This was primarily intended as a
  convenience for OEMs, but Microsoft did include a chapter (14) about the
  subject in the DOS manual.  I haven't found any better source on the
  subject; which means that I found practically no other information.  [Only
  other source: "Modifying MS-DOS Device Drivers" by Mike Higgins, Computer
  Language 3/85 - a good article which can clarify the DOS documentation, but
  does not treat several points explained here.] Assuming for the moment that
  driver software can be home-brewed, it is not an obviously useful technique.
  You could make your own driver for a 500 megabyte drive rather than waiting
  for the manufacturer to do it, but this is a last-ditch move.  However, a
  driver does not necessarily have to be controlling a physical device.  A DOS
  device driver must be a COM file, which limits the code space to 64K total.
  It has a specified header and function call structure.  DOS will only make
  and accept I/O operations which are given in the manual. You cannot return
  an error code other than those used by DOS, and most of those are not
  returned to your calling program.  Other than that, you can do as you like.
  This opens up many possibilities.  Driver software becomes a part of the
  memory-resident sections of DOS during the boot-up operation.  It becomes
  another resource available to any of your programs.  The classic example, as
  given in the DOS manual, is a ram-based disk simulator.  This is a "virtual"
  device, where the code and data is seen as a package by the operating system
  and user programs.  This module can perform any function which you can fit
  into a COM program, with predefined interfaces to DOS, other programs, and
  other device drivers.  Although Microsoft built some limiting assumptions
  into DOS which make it difficult to implement certain functions, many
  possibilities remain.  One option which I would like to explore is to
  offload a driver to an outboard processor for concurrent background
  operation.

_DOS Function Calls for Device Drivers_

  In order to keep things simple, I only used the "extended file management"
  (version 2.0) functions under system interrupt 21H. These are used by the
  "fread()" and "fwrite()" functions of the C86 C compiler.  The primary
  functions affecting drivers are:

    3D Open a file or device, return a 16-bit file handle in register
       AX.

    3E Close the file or device associated with the handle in BX.

    3F Read from a file or device.  The following registers must be
       loaded as indicated:
               BX => file handle of device
               CX => number of bytes to read ( 64K max)
               DX => segment offset of your data buffer storage
               DS => segment of your data buffer
       Reads CX bytes from a device into the buffer address given.
       *** What is not explained by Microsoft is that DOS actually
       requests only one byte per call to the device driver, making
       CX number of calls.  This has all sorts of ugly side effects,
       which will become evident in the description of my sample
       driver.  Microsoft has apparently built in the assumption that
       all character-oriented devices talk to fairly slow serial
       hardware, like printers.  If I read this right, DOS has the
       ability to respond to interrupts between each byte transferred,
       but it does make things clumsy.  DOS apparently increments the
       DS:DX buffer location after each call.  The driver will be
       re-run from START for each byte, and must maintain its own
       data pointers to maintain synchronism with the DOS transfer.

    40 Write to a file or device.
       Same as above, but data is transferred to your buffer area.
       *** Same warning.

    44 I/O Control for Devices.  This function has 8 subfunction codes
       which are used for some rudimentary device controls.
       Subfunction 2 is to read CX number of bytes from the "control
       channel" of the device, with the same register settings as for
       the normal read.  The stated purpose is to provide a way of
       reading device driver status rather than data from the device
       itself.  However, up to 64K bytes made be transferred per call.
       What your device does with it is up to you.
       Subfunction 3 is the corresponding write call.
       *** For these calls, DOS actually requests CX bytes from the
       device on one call.  This is used in the second version of my
       sample driver, which is much simpler than the standard
       read-write calls used in the first version.

_How DOS Translates Your Read/Write Function Calls into Device Driver Requests_

  When any of the above functions is called by your application program, DOS
  develops a data structure called the "Request Header" by the manual.  This
  structure consists of a 13-byte defined header which may be followed by
  other data bytes depending on the function requested.  The fixed part of the
  request header is as follows:

  _BYTE_       _PURPOSE_
    0  Length in bytes of the total request header (0-255)
    1  Unit code, used to determine subunit to use in block devices
         (not used for character devices)
    2  Command code (0-12) to activate specific device function
   3-4 Status word, returned by the driver
   5-12        The manual states that this area is "reserved for DOS".
       Another source indicates that this consists of two double-word
       (4-byte) pointers to be used to maintain a linked list of
       request headers for this device and a list of all current
       device requests being processed by DOS.  This is apparently
       in the works for a future concurrent-DOS.

  The 13 command codes are detailed on pages 14-12 of the manual; only the
  following are used by the character devices explained in this paper:

  _CODE_       _FUNCTION_
    0  INIT - perform all initialization required at DOS boot time
         to install the driver and set local driver variables.
    3  IOCTL INPUT - read a specified number of bytes from the
         device driver's IO control channel.
    4  INPUT - normal device "read".  Reads a number of bytes from
         the device your driver is controlling.
    8  OUTPUT - normal device "write" call from user program.
   12  IOCTL OUTPUT - write bytes to driver control channel.

  For each of these function calls, the driver receives the following:

INIT:  This function must be built into any driver program.  It is called only
by DOS during boot time, to reserve the system memory needed to hold the
driver and to link the driver into the set of active devices managed by DOS.
DOS sends:     13-byte request header
       BYTE number of units (not used by char devices)
       DWORD ending address of driver
       DWORD pointer to BPB array (not used by char devices)
The driver program must load the ending address at a minimum; any local
initialization may also be performed at this time.

INPUT, OUTPUT, IOCTL INPUT, or IOCTL OUTPUT:
  For all of these, DOS sends:
  13-byte request header
  BYTE media descriptor (not used for char devices)
  DWORD offset and segment of the data buffer in calling program
  WORD number of bytes to transfer in this call
  WORD starting sector (not used for char devices)
The driver must perform the requested read or write function, set the "number
of bytes to transfer" location to the number actually done, and set the status
word in the request header to indicate any errors.

  The actual use of these structures will be detailed in the driver function
  description.

_Required Structure for a Device Driver_

  Listing 1 (DOSDEV.ASM) is a template containing the minimum requirements for
  a character-oriented device driver.  This is detailed in pages 14-3 to 14-8
  of the DOS manual.  The driver program must meet the requirements of a
  normal COM file.  However, COM files usually start with an ORG 100H to allow
  room for the DOS Program Segment Prefix structure.  For a driver, you must
  use ORG 0, as the PSP is not used.  The Device Header data structure must be
  the first object defined in your file.  It consists of:
  DWORD        Pointer
         to the next device driver currently installed. This
         should be initialized to -1, DOS will fill this field as
         necessary during system initialization (boot).
  WORD Device attribute.  I used C000H to indicate that this is a
         character device with IOCTL capability.  This field is also
         used to indicate if this device is to be the standard output
         or input device.
  WORD Pointer to "device strategy" function in the driver.  This
         function is called whenever a request is made to the driver,
         and must store the location of the request header from DOS.
  WORD Pointer to function which activates driver routines to perform
         the command in the current request header.  This is called by
         DOS after the call to the strategy function, and should reset
         to the request header address stored by "strategy", to allow
         for the possibility of interrupts between the two calls.
  8-BYTES Name field.  For character devices, fill this with the name
         which you must use when opening the device.

  After this structure, you may include any local data definitions needed for
  the internal operation of your driver.  The DOSDEV example includes only the
  minimum; a pointer to the request header and a table of addresses of the
  functions which will be called by the command code from DOS. The function
  addresses are arranged according to their calling function code (0 to 12) so
  that the function router can use the DOS command code as an offset into this
  table.

_Required Device Driver Functions_

  For simplicity, I will discuss these functions as given in the DOSDEV.ASM
  listing.

  XDV STRAT:  This function is called directly by DOS when a request has been
made to use this device.  Its only purpose is to save a segment and offset
pointer to the request header.  At the time DOS calls the device, the segment
of the request header is in register ES and the offset is in register BX.
These values are copied into the variables RH SEG and RH OFF.  The fact that
Microsoft calls this a "device strategy" function leads me to believe that
more complex processing will be required in this function when DOS becomes
multi-user or multi-processing oriented.

  XDV FUNC:  This is called by DOS immediately after XDV STRAT.  The function
  pushes all machine registers to save the current data until the device has
  finished the requested operation.  Data segment register DS is set to the
  Code segment value, as all local variables exist in the code segment.
  Registers ES and BX are loaded from RH SEG and RH OFF to reset them to the
  start of the DOS request header.  The command code from the request header
  (at ES:[BX+2] ) is then used as an offset into the function address table
  FUNTAB to initiate the driver function requested.  In DOSDEV, only the INIT
  function has been coded, all others drop out to EXIT after setting the
  status word of the request header to "done; no error".  All you need to do
  is fill in the function code for any driver function you intend to use.

  INIT:  When DOS is booted, it reads your CONFIG.SYS file to determine which
  programs to install as device drivers (DEVICE=filename.ext).  After loading
  the file image into memory, DOS sends a request header with the command code
  "0" to the device.  The INIT function must load an offset (at ES:[BX+14])
  and segment value (at ES:[BX+16]) into the request header to indicate the
  ending address for the driver program, including space for any memory used
  as a virtual device.  The function may also do any initial variable setting
  within the driver.  INIT then exits back to DOS, which uses the address
  given to set the boundary of DOS including the new driver storage.

  EXIT:  This function restores all machine registers and returns to DOS.

_Examples of Character-Oriented Device Drivers_

  Listing 1 (STKDEV.ASM) and 2 (STKDEV2.ASM) show the use of a virtual device
  driver to implement a "stack".  User programs may "push" bytes or entire
  records by writing them to the device, and "pop" them with a read request.
  I/O control calls are used to set the record size to be used by the driver.
  This may not be very useful in itself, but this example shows solutions to
  most of the problems without being difficult to read.
    STKDEV is constructed in the recommended fashion; I got much of the code
  from the example device driver in the DOS manual.  Read and write calls from
  the user program activate the functions INPUT and OUTPUT, while IOCTL IN and
  IOCTL OUT are used to read and write the record size setting.  I developed
  the first version in a few days, but then spent two months of spare time
  trying to find out why it wouldn't work.  It's an undocumented feature of
  MS-DOS, although I can see some hints of it in the manual - now that I know
  what to look for.  When your user program makes a read or write call to a
  device, you send DOS the number of bytes to transfer, which may be 1 to 64K.
  You make one call to DOS (interrupt 21H). The request header for I/O
  contains a full word to contain the byte count sent from DOS.  I made the
  mistake of assuming that when I make a 10 byte I/O request to my driver, the
  driver would see a 10 byte count.  Actually, it sees 10 unrelated 1-byte
  requests from DOS.  STKDEV's INPUT and OUTPUT functions show the effects.  I
  had to establish two new variables (NUM2READ and NUM2WRITE) to keep track of
  how many bytes had been transferred, so that the driver would know if it was
  done with a "record".  This is required because the "top of stack" pointer
  (CURRENT) is set to the next free address following the last byte written.
  A "pop" operation (INPUT) requires decrementing the pointer by the record
  size, transferring a full record in the byte order written, then resetting
  the pointer back to the used record's start to allow overwriting and
  repeated "pops".  There must be an easier way to do this, but I think this
  mess shows the problems more clearly.
    STKDEV2 uses IOCTL functions rather than the standard I/O.  On IOCTL
  calls, DOS sends the full byte count in the request header.  This made
  things simpler in my driver code, but complicated my user programs by
  requiring custom read/write functions.  Take your choice.  DOS apparently
  starts at the buffer address which your program supplies in the I/O call,
  transferring one byte with a request to the specified driver, then
  incrementing the buffer pointer by 1, and repeating until the specified
  number of bytes is copied. The device driver must track this indexing
  carefully in some applications, for others it may not matter.

  Mike Higgins' article included many debugging tips.  One of them is the
  "yell" macro at the beginning of STKDEV.  This displays one character on the
  screen by writing directly to the video memory.  If you use DOS function
  calls to display the status of your driver, DOS will overwrite the request
  header which your driver has started processing.  I have left "yell"
  invocations throughout the function code; it was this macro that finally
  showed me what my device was receiving from DOS.

Functional Description of STKDEV.ASM:

  The procedure and device name is XSTK, which must be used when opening the
  device for I/O.  It is assembled and linked normally, then use EXE2BIN to
  convert the EXE file to COM form. I used EXE2BIN STKDEV.EXE XSTK.SYS,
  changing the file name because any references to XSTK once it is installed
  cause weirdness.  The CONFIG.SYS file must contain DEVICE=XSTK.SYS.  Reboot
  and XSTK has added 32K+ to memory-resident DOS.

XSTK STRAT:
  This is the "device strategy" function, which is called first by DOS for
  every request header. DOS has set ES and BX to the address of the request
  header; these are stored RH SEG and RH OFF to ensure that the driver will be
  able to find the request header.  It may be omitted for DOS 2.0.

XSTK FUNC:
  DOS calls this entry point second on all device requests.  The call is a
signal to begin processing the data in the request header.  DOS is now
suspended (in this version) until your device returns to it.  All machine
registers are saved on the stack, and ES and BX are reloaded to the address
stored by XSTK STRAT.  The command code at ES:[BX+2] is used as an index to
jump to the requested function.

INIT:
  This function is called only by DOS, only during installation (boot) time.
  As it will not be needed while the device is operating, INIT could be
  located after the end address returned to DOS, saving some memory.  STORAGE
  is the variable marking the end of the XSTK code.  However, I add 32K for
  stack storage.  This value is then copied to the request header and returned
  to DOS for memory allocation.  Local variables are set to default "stack
  empty" values.

IOCTL IN:
  Used to read the current record size from the driver into the calling
  program's data buffer.  In order to use the REP MOVSB instruction, CX is set
  to the requested byte count, DS and SI point to the internal variable
  RECSIZE, ES and DI point to the buffer address contained in the request
  header.  SI and DI are incremented by the REPeat prefix until CX bytes have
  been transferred.  ES and BX are then reset to the request header address.

IOCTL OUT:
  Write a new record size to the device.       Same deal as above, backward.

INPUT:
  Processes read requests.  The double word at ES:[BX+14] contains the address
  of the data buffer in the calling program, and the word at ES:[BX+18] is the
  byte count for the request.  This value will always be 1 for DOS 2.0, but
  this is subject to change.  The first process required is to check whether
  the previous write (OUTPUT) completed storing RECSIZE bytes.  This is done
  by checking the NUM2WRITE variable.  If NUM2WRITE is not 0, the CURRENT
  pointer is set to a record boundary before reading.  Next, INPUT checks to
  see if it is in the process of reading a record or if it is starting a new
  record.  If NUM2READ is 0, INPUT must reset CURRENT to the start of the last
  record written.  At this time, INPUT checks CURRENT against BOTMEM to ensure
  that reads will not go past the bottom of the stack space.  I tried to
  return an error code of 30H, to give my calling program a different error
  than those used by DOS.  However, DOS apparently checks this value against
  the approved list, and I get a "Disk drive error" on the display.  So, it
  appears that only the given error codes will be sent to calling programs.
  The actual read transfer is set up at PULLIT.  Again, I used the REP MOVSB
  instruction, even though DOS will only call for one byte per request header.
  CX is loaded with the count from the request header, DS and SI have been set
  to the proper address in the stack storage, ES and DI are set to the data
  buffer address of the calling program. NUM2READ is decremented on each
  request.  While NUM2READ is not 0, the value of SI is stored in CURRENT; SI
  has been incremented by the REP MOVSB to point at the next byte of the
  record.  If NUM2READ is 0, a full record has been read and CURRENT must be
  reset to the starting address of the record.  Finally, ES and BX are reset
  to point to the DOS request header.  The status word of the request header
  is filled with the code for "done; no error" and the process completes
  through EXIT.

OUTPUT:
  Similar to INPUT, except that CURRENT always increments.


Description of STKDEV2:

  This version reverses the use of IOCTL and INPUT/OUTPUT.  Most of the code
  is the same as STKDEV, but the variables NUM2READ and NUM2WRITE are no
  longer needed, as the DOS request header will request the actual number of
  bytes given by the calling program.  THerefore, the driver implicitly knows
  that each request will consist of a complete record.  If you compare IOCTL
  IN with INPUT, and IOCTL OUT with OUTPUT of STKDEV, it is obvious that this
  approach was easier to code for this application.


_Testing the Sample Device Drivers_

  Listing 4 (TXSTK.C) is a C program to perform simple test calls to STKDEV.
  Listing 5 (TXSTK2.C) tests STKDEV2 by using IOCTL calls in place of the
  read/write system calls used in TXSTK.

  TXSTK uses segread() to determine the DS segment value of itself.  This is
  used to pass DOS the segment value of the data buffer "instr".  Then XSTK is
  opened.  I used sysint21() calls instead of fopen, fwrite() and fread() just
  to simplify matters.  "Outstr" is then written to XSTK.  Although I fill
  callregs.cx with the count of 5, I know that DOS will make 5 one-byte calls.
  XSTK is currently set to the default RECSIZE of one, so a write and
  corresponding read produces "olleH" from my string "Hello" written.  I then
  use IOCTL calls to reset XSTK's RECSIZE to 5 bytes.  Although the following
  write and read are in the same form as before, XSTK now knows to treat input
  as 5-byte records.  So, "Hello" returns "Hello".

  TXSTK2 is the same through opening XSTK.  However, the first byte-at-a-time
  write/read must use a loop to cycle through the 5 characters of the output
  and input strings.  After resetting XSTK's RECSIZE to 5 using I/O calls, the
  write/read calls request 5 bytes, which is now processed in one call to
  XSTK.  The strings are returned as with TXSTK; "olleH" and "Hello".